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Subject: New list command - Revision 1 

The design of the new list command proposed in MTB-125 has been 
modified as a result of the design review. The changes made to 
the original proposal are summarized below. A draft MPM writeup 
of the revised design is attached. 

Changes to Proposed Features 

1. The ability to control the order in which entry types are 
listed, by typing their corresponding control arguments in 
the desired order, has been removed. It was felt that the 
undesirability of order-dependent control arguments 
outweighs any advantage of being able to vary the order of 
the listing. 

The change to the default order remains, however, and entrv 
types will now be listed in the order: segments, 
multisegment-files , directories, and links. 

2. The method of specifying which columns are to be printed has 
been changed slightly. In the original proposal, giving the 
control argument corresponding to a column caused that 
column, plus all those to its right, to be printed, unless 
-brief was also given. The default was -mode, causing mode, 
records, and names to be listed by default. 

In the revised proposal, by default, the names, records, and 
mode columns will be printed, but if -brief, or any of the 
control arguments corresponding to the default columns, is 
given, the default will be overridden, and only the names 
column (which is always printed), plus any columns named 
explicitly by control arguments, will be printed. 

Either or both dates will be printed, if their corresponding 
control arguments are given. Use of the date control 
arguments will have no effect on whether or not anv of the 
default columns are printed. 

3. The method of specifying which column to sort on was 
changed. Instead of typing one of the column-name control 
arguments after -sort to request sorting on the 
corresponding column, it will now be necessary to tyoe a 
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keyword that does not begin with a minus sign. The keywords 
will be spelled the same as the column-name control 
arguments (except for the leading minus signs), and both the 
ions and short forms will be accepted. It was felt that a 
value following a control argument should not have the same 
f orm as a control argument. 

4. Tne default of sorting on the leftmost column, when -sort is 
given without being followed by a column specification, has 
been changed. If one of the sort keywords follows -sort, 
the listing will be sorted by the specified column. However, 
if none of the keywords follows -sort, a default column will 
be determined as follows: if neither date is being printed, 
sort by name; if one of the dates is being printed, sort by 
that date; if both dates are being printed, sort by dtm. 

New Restriction 

The ability to give more than one -pathname argument (to 
specify that more than one directory be listed), will be 
removed from the command. A single -pathname argument, 
anywhere on the line, will cause only that directory to be 
listed, and, naturally, all starnames given on the command 
line will be searched for in that directory. The default 
will still be to list the working directory. The purpose of 
this is to eliminate all order-dependent control arguments. 

New Features 

1. The ability to sort by mode has been added. 

2. A new argument, -match, has been added, to request that, for 
multiply-named entries, only those names that match a 
starname be printed. (This is what the current list command 
does by default, but the default is being changed to print 
all names on the entries selected for listing.) 

3. New control arguments: -from (-fm) date__time and -to 
date_time have been added, to reauest that only entries 
having dtm or dtu between the specified dates be printed, 
dtm will be used for this purpose in all cases except when 
dtu is being printed or sorted on, and dtm is being neither 
printed nor sorted on. 

If -from is omitted, entries from the earliest date_time 
thru the -to date_time will be printed. If -to i3 omitted, 
entries from the -from date_time thru the current date_time 
will be printed. The given date_times must be strings 
acceptable to convert_date__to_binary_, and the -to date_time 
must be later than the -from date_time. 

4. A new control argument, -exclude (-ex) has been added, to 
specify that entries matching a given starname be excluded 
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from the listing, rather than being included. This new 
argument will precede each starnarae whose matching entries 
are to be excluded. It will be possible to give both include 
and exclude starnames on the same command line, and only 
entries that meet both criteria will be listed. That is, 
entries matching any of the exclude starnames will be 
excluded from the listing, and from the ones that remain, 
those that match any of the include starnames will be 
listed. 

Documentation 

The attached MPM writeup says that the default order, when 
no sorting is specified, is the order in which entries are 
found in the directory, and that -reverse without -sort will 
reverse this order. 

Some readers of this MTB might interpret this as a change in 
the present operation of the list command, knowing that new 
entries are added to the end of a directory, with the oldest 
entries remaining at the beginning, and the list command 
deliberately reverses this order, printing the newest 
entries first. In fact, the operation of the command is not 
changing, but the MPM writeup is being simplified by the 
removal of the above detail. 
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NAME: list, is 

The list command prints information about entries in a single 
directory. Arguments allow the user to specify the directory to 
be listed, the entry types, names, and dates for which 
information is to be printed, the amount of information to be 
printed for each entry, and the order in which entries are to be 
listed . 

The default, when no arguments are given, is to list files 
(segments and multi-segment files) of all names, in the working 
directory. For each entry, the mode, records used, primary name, 
and any additional names, will be printed. The two entry types 
will be listed in the order: segments, multi-segment files; 
within each entry type, entries will be printed in the order in 
which they are found in the directory. Preceding the listing of 
each entry type will be a line giving the total number of entries 
of that type and the total records used. 

USAGE: list -entry_names- -control_arguments- 

1) entry__names are the (optional) names of entries to be 

listed. If entry names are given, only 
entries having at least one name matching one 
of the entry names will be listed. The star 
convention may be used in the entry names. 
Except when the -exclude control argument is 
used, the positions of the entry names 
(before, after, or among the control 
arguments) have no significance. 

2) control__ar guments may be chosen from the following:: 
-pathname dir_path 

-pn dir_path causes the directory dir_path to be listed, 

instead of the working directory. 

The following control arguments are used to soecifv the entry 
types to be listed: 

-segment, -sm print information about segments. 

-mult i segment _f ile , 

-msf print information about multi-segment files. 

-file, -f print information about files (i.e., segments 

and multi-segment files, in that order). This 
is the default. 

-directory, -dr print information about directories. 

-branch, -br print information about branches (i.e., 

segments, multi-segment files, and 



MTB-149 



Pa?e 



directories, in that order). 

-link, -lk print information about links. 

-all, -a print information about all entry types 

(segments, multi-segment files, directories, 
and links, in that order). 

The following control arguments are used to specify whether 
totals information, or detailed information for each entry, or 
both, should be printed: 

-total, -tt print only the heading lines giving- total 

entries and total records used, for each 
entry type specified. 

-no_header, -nhe omit the heading lines (which are printed by 

default when detailed information about each 
entry is being printed). 

The default is to print totals information, plus detailed 
information for each entry. When detailed information is beine? 
printed, it is arranged in columns, in the order (from left to 
right): date-time modified, date-time used, mode, records used, 
names, name count. By default, only the mode, records, and names 
columns are printed. If the -brief control argument (see below) 
or any of the control arguments corresponding to these default 
columns is given, then this default is overridden, and only the 
names column, plus any columns selected explicitly by control 
arguments, will be printed. 

The following control arguments are used to specify which columns 
should be printed: 

-name, -nm print the names column. 



-record, -rec print the records column, 
-mode, -md print the mode column. 

-date__time__used , 

-dtu print the date-time used column. 

-date_time_modified , 

-dtm print the date-time modified column. 



The following control arguments are used to specify the printing 
of information about multiply-named entries: 

-primary, -pri print the primary name, but not the 

additional names, of multiply-named entries. 
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-match 



entries . 



print only those names that match one of the 
given starnames. 

ilt is to print ail of the names of multiDlv-named 



-count, -ct 



for multiply-named entries, print the total 
number of names. 



The following control arguments are used to decrease the amount 
of information printed, or cause it to be printed in a more 
compact format: 



-brief, -bf 



-short, -sh 



This argument has two meanings, depending on 
whether or not detailed information is being 

printed. If just totals information is being 
printed, this argument will cause the totals 
information for all selected entry tynes to 
be abbreviated and printed on a single line. 
Otherwise, it will suppress the printing of 
the default columns when they are not 
explicitly named in control arguments. For 
example, list -dtu -brief will cause names 
and date_time_used , but not mode and records, 
to be printed, 

print link pathnames starting two spaces 
after their entry names, instead of aligning 
them in column 35. 



Tne items: mode, records, and date__time_used have no meaning for 
links, and there is an additional item, link_path, associated 
with each link. There is no control argument to specify that 
link_path should be printed. It will be printed in all cases 
except the following: 

1) when only totals information is being printed; 

2) when the only column being printed is the names column; 



3) when the -brief control argument is given. 

The following control arguments specify the order in which 
entries will be printed, within each entry type: 

-sort sort_key sort entries according to either name, 

records, mode, date__time__used , or 

date_time_modif.ied , as specifed by the 
sort_key, or by the default described below. 

The sort_key can be one of the following keywords: 
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name, nm sort entries by primary name. 

record, rec sort entries by records used (largest first). 

mode, md sort entries by mode. 

date_time_used , 

dtu sort entries by date_time_ used (most recent 

first). 

date_time_modified , 

dtm sort entries by date__time_modif ied (most 

recent first; . 

If sort_key is omitted, the default column on which to sort is 
determined as follows: if neither date is being printed, sort by 
primary name; if one of the dates is being' printed , sort by that 
date; if both dates are being printed, sort by date-time 
modified . 

Links can only be sorted by name or date-time modified. When 
sorting by any other column is specified, links will remain in 
the order in which they are found in the directory. 

If -sort is not given, entries will be printed in the order in 
which they are found in the directory. 

-reverse, -rv This argument is used to reverse the order in 

which entries are printed. If -sort is also 
given, the sort will be reversed. Otherwise 
entries will be printed in the reverse of the 
order in which they are found in the 
directory. 

The following control arguments ae used to specify that only a 
subset of all entries in the directory be listed: 

-exclude entry_name 

-ex entry__name do not list any entries that have a name that 

matches entry_name. The star convention can 
be used in entry_name. 

Multiple exclude entry names can be .eiven 
(each immediately preceded by the -exclude 
control argument). They will operate top-ether 
with include entry names (those not precede6 
by -exclude), to limit the entries listed. 
Ail entries having a name that matches any of 
the exclude entry names will be excluded from 
the listing, and from the entries that 
remain, all those that have a name matching 
any of the include entry names will be 
listed . 
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The following control arguments are used to limit the entries 
listed to those having date-times (either date-time modified or 
date-time used) before or after specified date-times. The 
date-time that is used in this comparison will be date-time 
modified, in all cases except when date-time used is being 
printed or sorted on, and date-time modified is neither being 
printed nor sorted on, in which case, date-time used will be used 
in this comparison. 

-from date- time 

-I'm date-time do not list entries whose date-time (selected 

as described above) is before the specified 
date-time. 

-to date-time do not list entries whose date-time (selected 

as described above) is after the specified 
date-time . 

If both are given, the from date-time must be earlier than the 
date-time. The value after -from or -to must be a string 
acceptable to the convert_date_to_binary_ subroutine, described 
in MPM Volume III (Subroutines). If the date-time string contains 
blanks, it must be enclosed in quotation marks. Note that the 
from and to values are date-times, and that the default time 
supplied by convert_date__to_binary__, when only a date is given, 
is Midnight. Therefore, to list entries modified on a certain 
date, use -from that_date -to next_date . 

EXAMPLES: 

list -pri -ct 

lists all files in the working directory; for multioly-named 
files, the primary name is printed, but not any of the secondary 
names , a nd the total number of names that the file has is printed 
after the primary name, on the same line. In addition to the 
names column, the mode and records used columns are printed. 
(This is the default, and it will not be mentioned in the 
examples below, when only the default columns are printed.) 

list -sm *.* -ex *.pl1 

lists all the segments in the working directory having 
two-component names whose second component is not "pll". 

list -ex * . * 

lists all the files in the working directory having other than 
two-eonponent names. 



list -dtm -sort 
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lists all files' in the working directory, sorted by date-tine 
modified. Tne date-time modified column is orinted, in addition 
to the mode, records, and names columns. 



list -name -sort dtm 



lists all files in the working directory, sorted by date-time 
modified. Only the file names are printed. 

list -sm -name -pri -nhe 

lists the primary name of each segment in the working directory, 
without printing a heading line or other extraneous lines. 

list -mode -pri 



lists the mode and primary name of each file in the working 
directory. 



